MacFormat 1995 March/macformat-022.iso/Shareware City/Applications/Graf ƒ/Readme 2.1.1

Text File | 1994-11-23 | 27.4 KB | 550 lines | [TEXT/GRA1]

    Preliminary notes: v 2.1.1
    -------------------------

Disclaimer: These notes are a guide only, they do not constitute a user manual.

“If this program proves useful to anyone out there then fine, if not then that's fine too.”


    New for 2.1.1:
    ------------

• One bug fix: stops crash when selecting a plot window when data window palletes
are showing!!   This is such a bad bug that a new version was needed immediately.
Don't use v2.1.0

    Introduction:
    ------------

Graf is object oriented in the way it handles data and plots. This means that each set of data has the
information on how it wants to be plotted, and each plot has its own formatting information and a
list of data to plot.

This is implemented through popup menus, thus Graf requires at least System version 6.0.2 to
operate. It will of course operate with all newer versions.   It is system 7.0 friendly, 32 bit clean
and compatible with all macs from the mac plus up to the Quadra 950 and beyond.

There are three kinds of windows in Graf. The first it the data windows, such as this one, then the
plot window type for graphs and finally the stat window for statistics.  Each kind of window
has its own popup menubar to set up the various parameters needed for the final plotting.

    The data window menus:
    ----------------------

• Marker: This menu allows the symbols and error bar styles to be set for the data points when
they are plotted. The current selection is shown on the menubar beside “Marker”.

•Symbols: This menu graphicly shows the available symbols.
This menu is a 'tearoff' just like some hypercard menus.

•Size: This is the size of the enclosing box that the symbol is drawn in (the box is not drawn). The
“Other…” option uses the resource picture to show size changes graphicly. Note that when a high
resolution printer is used, the PICT format of symbol will automaticly take advantage of the higher
resolution and in general the symbols look best on the final output (where we want them to).

•Errors: Graf allows for independent +Δx, -Δx, +Δy and -Δy errors. The first 6 options are
various styles of errors, from none to ovals, the last two options are vector plot options, where
the Δx and Δy terms are not errors, but actually form a vector with the main data point. One
option has little arrow heads and the other is symmetrical about the data point and is bi directional.
This menu is now a 'tearoff' just like some hypercard menus.

•Line: This menu specifies the way in which data points are joined. The current selection is shown
on the menubar beside “Line” as a line in the selected style, and a small icon to show the joining
method.

•Pensize: is the thickness of the pen in point/pixels, On the screen widths less than one are
displayed as one. On high resolution printouts the actual thickness asked for is used.

•Pattern: shows the system list of patterns, to use in drawing the line. The 'plain' grays have
postscript grays substituted when printed, other bitmaps are copied. If you really want a different
pattern, then warm up ResEdit and make your own PAT# resource in Graf....
This menu is now a 'tearoff' just like some hypercard menus.  It will grey out when the
active window is not a data window.

•Style: determines the methods of joining points, from a simple straight line to no line at all. The
rectilinear methods are useful for discrete, binned data where the value corresponds to the centre,
right or left edge of the bin. The smoothed option is a parametric quadratic bezier curve
using the data points  and as off curve controls and data point mid points as on curve controls.
This menu isa 'tearoff' just like some hypercard menus.   It will grey out when the
active window is not a data window.

•Form Polygons: If this item is chosen, then the line segments will be grouped into macdraw style
polygons rather than simple groups. So, if you want a spline smoothing, then edit the plot with
macdraw, select the line and choose the smooth option...

•Setup: This is where the x,y and error columns are assigned, and any scaling or offsets are
applied. Once the columns and offsets are determined (or defaulted) then these plus the Marker and
Line settings constitute a 'setup'. With multicolumn data, it is often desirable to plot several
different pieces of information,in different styles, so each data window actually has a list of
setups, starting with the initial
'1 of 1' . New, independent settings can be defined by adding new setups to the list with the little
arrows. the single arrows navigate up and down the list, adding new setups if needed. The double
arrow is used to reduce the total list of setups.  When a data window is plotted, it is actually
plotted a number of times, once for each setup in the list.

•The 'Tabbed data' option refers to typical mac spreadsheet tab delimited data. Without this option
strings of tabs are regarded as as single column setting. When this options used then each tab
indicates a new column. This item is necessary for tabbed spreadsheets with missing entries in
some positions.

•When 'Use Separators' option is used, Graf assumes that when a text line (ie not a number line)
is encountered, the current curve ends and a new one is started when the next numbers are
found. ie

        0.1    0.1
        0.2    0.2
c
c coments, anything really
c
        0.3    0.3
        0.4    0.4

would be plotted as one continuous curve normally, and as two separate ones when 'Use Separators'
are used.

•Text: The data windows are text files, and behave like a very simple word processor (hence this
document). So each data has a Text menus for changing the appearance of the data only, this has no
effect on the plotting operations at all.

The data in the data windows is organised as follows:

•The data is in a 'free form' text style, unlike the more common cell or spreadsheet style. This has
a number of advantages and disadvantages:
•The best advantage is that virtually any TEXT document can be read in a view in a readable and
sensible manner. Special column separators and so on are *not* needed.
•The worst disadvantage is that manipulating columns of data is very difficult. Graf is NOT an
analysis program, and any spreadsheet like fiddling should be done before entering Graf. A
Multifinder setup with excel and Graf works very well, with Graf providing the high quality
graphics that Excel lacks.
• The data is still conceptually organised in columns, with the columns being defined on a line by
line basis. That is, columns only exist on lines that have columns of numbers, and any line can have
any number of columns from 0 up.
• Graf uses a fairly clever interpreter to get the information from the data. This means that
enormous data arrays are not needed, in fact only 6 binary numbers are needed (x,y,+Δx,-
Δx,+Δy,-Δy) at any one time. It has also been introduced to the output from various makes of
computers and can handle data with line feeds or without for example.
• The following is a conceptual description of how Graf reads the data files:

    i) Check the first non-space character on a line,Column counter = 0,
    ii) If it is a numerical character then goto 4
    iii) Skip line and goto 1
    iv) increment column counter
    v) Read in characters until a non-numerical character or newline is encountered
    vi) Form a number with the characters so far.The numbers that correspond to your column
    settings are plotted and the rest are skipped.
    vii) read more characters, goto 2.
    {this is VERY conceptual}

•Put Simply: any line that doesn't begin with a number is skipped. Columns of numbers may be
separated by *any* non numerical characters(including tabs). Columns are read along a line until
the line runs out or the  required columns have been read. Any time a required number fails
to evaluate (ie a malformed number or  missing columns, a value of zero is used, mostly so
the problem is visible and corrections can be applied).
•Individual window may only contain 1 GigaByte of  characters. If a larger data file is read, Graf
will crash! :-) Ha Ha!

    The plot windows menus:
    -----------------------

• The most important menu in the plot window is the “Data sets” menu. This is a dynamic, changing
menu that shows the list of available data to plot. By selecting data window with this menu, the plot
window accumulates the list of data to plot. When the draw button is pressed, this list is processes
sequentially, in the order they were selected. If a data window consists of a series of setups the
these are cycled through before the next data is processed. Each data set is plotted in the style
defined in the manner defined in their respective setups in their respective windows.
• The first item selects a dialog box that has all the data sets in a list.  You can select
multiple sets at one go.

•Axes: this menu defines the basic appearance of the plot.

•Size refers to the size of the rectangular frame that the plot is drawn in. The dialog box that come
up is designed to work in pixels as this is the only way to be sure of the final result. There are x2
and /2 buttons for scaling up and down easily, useful for when you want to print at some sort of
reduction on your printer.
• Ticks: Tick spacing are in terms of the data units, tick lengths are in pixels. The Autoscale button
provides 'semi-automatic' scalings of ticks to the current range. A warning will appear if you
choose a ticks spacing that will produce hundreds of ticks, either redo the spacing or use the auto
scale option.
•Range: determines the data values that will be plotted. Data points outside this range will not be
plotted.  If all points fall out of range during a plot then a warning is given.
•Scales: This is where you can choose normal, log-normal and log-log plotting, to various bases.
The data is “logged” and the plotted on normal linear axis, there are no silly uneven spaced ticks.
•Numbers etc: This section of the Axes menu determines the setting for the axes numbers!
•Labels:This menu is the implementation of labelling in Graf. It provides for a title, x-axis label and
y axis rotated label. In addition a legend facility is available. For more fancy labelling, save the plot
and post edit it with a program like macdraw.
•Thickness: is the thickness of theframe and ticks in point/pixels, On the screen widths less than
one are displayed as one. On high resolution printouts the actual thickness asked for is used.

Each submenu give independent control over the content and style of each label. The dialog boxes
ask for a string (up to 40 chars) and a location (in pixels) for the label. The labels are centered on
the location The labels can be drawn or not drawn, and have an optional frame.

The names used in the legend come from the columns setup for the data sets.  The lines/marker
styles are read from the data setups.

• Special: This menu contains a group of miscellaneous items.
• Preview…: This item brings up a small floating winowoid that displays the current plot and the
number of pages needed to print it using the current page setup.  As the plot size and/or pagesetup
change this window will resize to reflect the page layout.  It will not grow too large however and
should always remain a relatively small proportion of a 9" Mac screen in size.  You cannot
manipulate the plot layout with the windoid. (Yet!)

•Overlays: this is a list of plot windows. This list is drawn in the current plot window before the
current plot is drawn. In this way multiple plots can be layed out on one page. In addition, Graf can
read any PICT file into a plot window, so some fancy background pictures could be used for your
plots.

•The Draw button: In general, drawing the data is a slow business, compared to the frame and axes
etc. So While all the plot formatting is redrawn automaticly, no data is plotted until the button is
pressed.  When there are few data points, this is no problem, and when there are many, it is much
easier to get everything just right and then plot the data last.

The data plotting can be interrupted on a set by set basis. That is 'command - .' will stop the
current set being plotted, and the next set if any will be commenced. For a single set this will then
stop the plotting and for multiple sets, multiple interrupts may be needed. This was done to allow
finer control over the interruptions, particularly is you want to skip forward over sets to have a
look at how a later set will look.
During plotting, the data window being plotted is displayed in the bottom left 'information' box in
the plot window. A percentage shows how much of the file has been read (not how many data
points), in ten line  steps. With multiple setups, one file name will be shown with the setup counters
incrementing several times.

•The Auto button: Same as draw, with a prior scan to set the ranges and ticks.

    Graphical plot manipulation:
    -------------------------

Frame:
•A single-click-drag in the plot frame allows the user to reposition the frame, the frame etc will
be redrawn, but not the data.
•A double-click in the frame will bring up the size dialog.
•The bottom right corner of the frame is a resizing corner for clicking and dragging. Labels &
Legend:
•A single-click-drag in the labels allows the labels to be relocated. In a layered system, the labels
are on top of the data and frame.
•A double-click in a label will bring up the appropriate dialog. Ticks:
•A double-click in the lower x axis ticks or left y axis ticks will bring up the range dialog.
•A option-double-click in the lower x axis ticks or left y axis ticks will bring up the ticks dialog.

Numbers:
•A double-click in the numbers will bring up the numbers dialog.

    Label Styled Text.
    -----------------

Text for lables and the legend (via the data columns dialog) can be styled.  It is a plain
text formatting method similar to Word formulas and TeX.
Here is a summary.  'Arg' stands for any expression, including other fomat statements,
from one character up to whole expressions. Examples here can be cut and pasted into
a plot title dialog to see how they look.

{Arg1 Arg2}        Curly braces group many Args into one Arg
            Formats such as italics are contained within the
            braces, this is a good way to stop italics from breaking out.
            Example: See below.

\-            Plain text, stops all other settings.
            Example: {\! Tex\-t} will make the first three lettes in italics
            and the last in plain text.

\!            Italic text.
            Example: Hello {\! everyone}  eveywhere!
            will make the first and last words plain letters, and 'everyone' in italics.

\@            Bold text.
            Example: I'm so  {\@ FAT}!
            will make the first words plain letters, and 'FAT' in bold.

\&            Bold & Italic text.
            Example: I'm so  {\& indecisive}!
            will make the first words plain letters, and 'indecisive' in bold-italic.

\$            Symbol Characters
            Example: {\$ abg}
            will show as alpha beta gamma. Useful in H{\$a} for hydrogen
            spectra.

\^            Super Script next arg
            x\^2
            will make x squared.  May look better as {\!x\^2}

\^            Sub Script
            Example: H{\_2}0 will make the water molecule.
            Example: A{\_long superscript}

\§{arg}{arg}         Super Sub Script the next two args are used as simultaneous super
            and sub scripts.
            Example: SO{\§{2+}{4}}

\\             Backslash, since \ is used for the other commands

\}            Right Bracket, since } is used for grouping

\{            Left Bracket, since } is used for grouping


    The Stat windows menus:
    -----------------------

• The most important menu in the stat window is the “Data sets” menu. This exactly equivalent
to the data sets menu in plot windows, see above.
• The first item selects a dialog box that has all the data sets in a list.  You can select
multiple sets at one go.

    General Notes:
    -------------

The fine lines in Graf do not require page reduction for printing, a good result will come from 100%
page sizes. If you are attempting to make multiple line segments look smooth however, consider
drawing a large plot and reducing the printout, this reduces the quickdraw integer coordinate
rounding errors which depend on the resolution that the plot is drawn at. That is if you have 2000
pixels to choose from compared to 200 ,say, the a better accuracy will be achieved.

Graf knows what resolution the printer is using, so you do not have to use the precision bitmap 4%
reduction etc, and a 25% reduction really maps to 300 dpi on the laserwriter. The page breaks for
the plot, using the current page setup are drawn in 3 pixel wide stripped lines, these lines are NOT
printed. These lines are centred on the page break.

The normal menubar menus are standard menus, plus a Data window to display data windows, and a
plot menu for finding plot windows. The “Hide” file option simply makes the window invisible, the
window still exists and can be plotted etc, the appropriate menu will redisplay the windows.

In principle there are no limits to the number of windows, size of data or plots etc in Graf, however
the current version will only handle upto ~256 windows and 100 column data and any number of
setups! This is all limited by your available memory, but graf will work in ~400K of RAM with 10
or so windows. Check the about… item for your current free memory. If you get low on memory
then you will be given the opportunity to save your work and quit. Try the usual methods to
increase your RAM available for the program if this happens.

    General Setup:
    --------------

Default settings can be defined by setting up a window in the desired format and saving it under a
special name. For default text settings name the file 'Default Text' (case is important), and use
'Default Plot' for a default plot setting. When new blank windows are required, Graf will look for
these files in the same directory as Graf, and in the system folder. If they are found then they will
be loaded in as Untitled-x or Plot-x (where x is a number). If they are not found then internal
defaults are used.

The Preferences menu item 'Auto draw plots' is the same as using the draw button all the time. This
is only really useful for small data sets when drawing is quick.

The Show Floats item will only be available once a floating palette/menu has been torn off. The
show /hide operations will only apply to the currently 'torn' menus.


    Questions, Suggestions and Bugs to:
    ---------------------------------

        Ralph S. Sutherland.
        JILA
        University of Colorado
        Boulder, CO, 80309-0440
        USA

    email:

        [e-mail]
        [e-mail]

Cheers

Ralph   (Feb 1994)


PS    Complete Version History
    -----------------------

    New for 2.1.0
    -------------

bug fixes:
• Worked around a persistent crash when opening files in 32 bit mode.  No icons in lower list
until a fix is worked out.
• Added Startup Splash-Screen
• Improved scroll bar updates (as usual :-) )
• Added some new quit options  'Quit and save all' and 'Quit and don't save'.
These are*Really* useful when you have about 40 files open and can save a lot
of time.  But be careful with the don't save option.
• Improved the columns setup dialog to allow the user to switch through all the
current setups of all the windows using a popup menu.

    New for 2.0.5-9
    ---------------

• Mysterious Hiatus that will go undocumented.

    New for 2.0.4
    -------------
minor bug fixes:
• Fixed cursor keys for data and stat windows
• Simplified About dialog
• Fixed editing crash during low memory conditions.
• Font menus now act as advertised below.  There is only one menu in the resources now.
you can modify it as you please with ResEdit to show your own favorite set of fonts.
Graf 2 will automatically disable unavailable fonts.  All the font menus in the program will
be the same as the single resource copy.
• Sounds now default off.
• Slightly changed menu click areas on window menubars to include symbol disply areas
as well as drop boxes and text.
•  Fixed plot preview.
• 'Auto plot' should now cause plots to erase properly before replotting.

    New for 2.0.1, 2, 3
    -----------------

minor bug fixes:
• Data list selection bug *really* fixed.
• Data list selection buttons work.
•  v1.4.3 plots with Y lables load correctly.
• Text menu in stat windows fixed.
• Fiddled with scrollbar adjustment.
•  Slight change in parsers to correctly ignore lines with leading spaces and no numbers.
• Fixed test size display updates.

Remaining features:
• Arrow keys don't work

    New for 2.0: Major version upgrade
    --------------------------------

General:

• All visible text and words in menus and information areas are  stored as string
resources so that localization to other languages is conceivable.
• Whizzy new colour menubars in windows.   Color coded:  data - red, plot - blue,
and new statistic windows use green.
• Most modal dialog boxes can be dragged around under system 7.x
• Active window is checked on the main menubar wind list menus.
• Sounds can be turned off when they are too annoying.
• Completely new statistics and line fitting capabilities using new 'stat' windows that
are similar to plot and data windows.  More details below.
• Undo
• Floating windows no longer keep disappearing when other windows are selected.
inappropriate floating windows are simply grayed out when they don't apply to
the active window.
• Background processing improved.
• New finder icons, you may need to rebuild your desktop to see them though.
• The font menus is organised by typeface type, ie mono-spaced, serif, sans-serif and fancy.
• The menu is predetermined and may be edited with ResEdit if you have a different favorite set.
Any font on the menu that is not found at startup is simply greyed out.  Having the predetermined
typeface sets greatly speeds up startup on machines with many fonts installed.
• New styled text, such as super and subscripts is implemented for plots and display text
in general.
• A set of example files, data, stats and plots are given to show the neat features of Graf.

Data Windows:
• New text editing library, the programmers editors package v1.0, allows the
editing of large data files.  No more load headers, you can edit a multi-megabyte
file if you have the RAM.
• Undo allowed in text editing.  Can be disabled when memory is low.
• Tabs are supported in the new text editing, can make data files look a lot better. (see below)
• Multiple data sets in one data window are possible, any non numerical line
breaks the plotting and starts a new curve.  See examples.

Plot Windows:
• New data set selection mechanism using a list dialog is available to make selecting
multiple data sets to plot *much* easier.
• Automatic range setting with a new button.  The Auto button first scans the data sets to
chose an appropriate range and domain to plot, sets the ranges and ticks, and then does a
normal plot.  This is somewhat slower than a normal plot, but it can be a real timesaver
if used once, followed by normal draw commands.
• A resolution option for the y-axis label allows high resolution printing of the
y-axis lable on non-postscript printers.
• Title, axis and legend text can be formatted to have super/subscripts etc.  A format
button in the label/title dialogs shows the possibilities. See also the new example files.
•  Progress display is different, neater and nicer.  (IMHO)
• Progress is faster.
•  Double Click algorithm changed.
•  Page placement of plot can also be manipulated by dragging the reduced view in the
plot preview window.
• Numbers can be placed on any, all or no axis. See numbers dialog.
• logs of negative number magnitudes may be taken using the log(|x|) option in the
scales dialog.
• The plot frame may be omitted, using the size dialog.  This is useful for curves that are
going to be overlayed.


Stat Windows:
• All new :-)
•  Simple statistics.  On direct and log transformed data
•  Unweighted, Experimental errors, Gaussian weight and Poissonian weights.
•  Linear and polynomial regression fitting.  Up to 6th order fits, beyond that
it stops being physically realistic.
•  A cubic spline fitting routine is available.  This need monotonic x data.
Thanks to Roland Kjellander for the algorithm.
•  Some unfinished routines are disabled.
• There are a number of result output options.
• Results can be pasted into a plot window and plotted, or saved as a stat
or a text file.
• A calculate button, analagous to the plot draw button, starts the calculations.
• Data set selecton is the same as in plot windows.

Bug Fixes [well, just the biggest ones:-) ]

• The funny double shuffle (maybe that was only in 1.5.8) when closing windows is gone.
• The intermittent crash when closing many data windows is gone, really.
• Other memory problems, some of which may have been related to pre-crash
conditions from the data closing crash, appear to be fixed.
• Low memory recovery is more robust.
• Misc Cosmetic bugs fixed.

    New for 1.5.8
    -------------

The dark years....1993-1994  There were more bugs than features in version 1.5.8.  I'd rather
not talk about it.

    New for 1.4.2/1.4.3
    -------------------

• System 7.0 Publish and Subscribe!  Allows for publication of plots and subscription of
data.  By combining Auto redraw for plots and a new auto publish options, Graf can serve as
a plotting facility to any program that can publish and subscribe.
• Enabled the colour option for the marker symbols at last.  (They used to be stuck as black)
• Resolved design problems with 'Header' data windows. The file name is nolonger suffixed
with the '-Header' text.  The info box now displays tiny status icons that differentiate the Header
files from normal data files.  This fixes problems with file names on disk.
• Can operate in the background.  This is useful for publish/subscribe server setting and for
future releases of Graf with Apple Event control.
• Standardised the dialog button locations to suit the system 7.0 user interface guidelines.
• New smoothing algorithm based on bezier curves to give a truely parametric smoothing.  This
means that you can smooth a spiral if you really want to.
• Faster columns allocation dialog, you can now jump forward and back by 6 columns at a time
by clicking in the numbers part of the 'scrollbar'.  The click sound has been removed as well.
• Plot page preview windoid.  Useful for Macs with small screens, this will reduce the need
for scrolling around to check the page layout for big plots.
• Changed Default Text and Defaul Plot mechanism.  You now need to place the default files
in the system folder on the startup disk.  The preferences folder is not used to maintain System 6
compatibility without undue coding complications.
• Reorganised plot window menus. Overlays is now a submenu of a 'Special' menu which
includes the new page preview option.
• Added cooler colour buttons/icons etc for those with colour macs.
• Improved tearoff menus so that they don't tear off so easily.
• Upgraded the line style menus to bring it in line with the style of the other tearoffs.
• Fixed bug where last byte in data file was ignored (Thanks John)
• Fixed colour menu so that the colour items remain coloured.
• Finally fixed text scrolling (Applause!).
• Many minor bug fixes, to numerous to mention (well, this is freeware)

    New for 1.3.1/1.3.2
    -------------------

• Figured out 68000 mac  (Plus, SE etc) QuickDraw bug work around.
Stops crash on startup when using a default plot.  I should never have sold my mac plus....
• Also for 68000 mac owners, speed up in text input.
• Fixed crash upon quitting without saving any modified files

    >>>>>>>>>IMPORTANT: New for 1.3.0<<<<<<<<<<
    --------------------------------------------

• Fixed a bug when saving large files (ie Header windows) that would otherwise cause all
but the first 28k to be missing from the saved file.  This may cause data to be lost.  Please
stop using ANY version before 1.3.0.
• Fixed a bug caused by cosmetic plotting bug fixes.... (see v1.2.6)

{Stuff about eariler versions deleted}